home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / FAQSYS18.ZIP / FAQS.DAT / XM.TXT < prev    next >
Text File  |  1995-09-04  |  13KB  |  382 lines
  1.  
  2.        The XM module format description for XM files version $0104.
  3.  
  4.        By Mr.H of Triton in 1994.
  5.  
  6.        - Be prepared! Are you sure you want to know? :-)
  7.  
  8. << A LOT of comments, corrections and notes added by Guru and
  9. Alfred of Sahara Surfers in 1995. All additions are included in
  10. double angle brackets << like this >> and everything outside
  11. them is left intact. Note the HUGE amount of errors in the
  12. original text. Triton: Perhaps you'd like to include THIS in the
  13. next FT2 release? :-)
  14.  
  15. Not copyrighted, released into public domain (at least the
  16. additions by us). Feel free to do what you wish. Credits please.
  17.  
  18. Remember - the added information is based on REAL XM files. >>
  19.  
  20.  ============================================================================
  21.  
  22.  
  23.    ******************************
  24.    *   The XM file structure:    *
  25.    ******************************
  26.  
  27.    Offset Length Type
  28.  
  29.       0     17     (char) ID text: 'Extended module: '
  30.                 << Nope: 'Extended Module: ' >>
  31.      17     20     (char) Module name, padded with zeroes
  32.      37      1     (char) $1a
  33.      38     20     (char) Tracker name
  34.      58      2     (word) Version number, hi-byte major and low-byte minor
  35.             The current format is version $0103
  36.             << Nope, it's $0104. Format versions
  37.             below $0104 have a LOT of differences.
  38.             Check this field! >>
  39.  
  40.      60      4    (dword) Header size
  41.             << Calculated FROM THIS OFFSET, not from
  42.             the beginning of the file! >>
  43.      +4      2     (word) Song length (in patten order table)
  44.      +6      2     (word) Restart position
  45.      +8      2     (word) Number of channels (2,4,6,8,10,...,32)
  46.     +10      2     (word) Number of patterns (max 256)
  47.             << Might not include all patterns used - if
  48.             empty patterns are used at the end of the song
  49.             they are NOT saved to the file >>
  50.     +12      2     (word) Number of instruments (max 128)
  51.     +14      2     (word) Flags: bit 0: 0 = Amiga frequency table (see below);
  52.                       1 = Linear frequency table
  53.     +16      2     (word) Default tempo
  54.     +18      2     (word) Default BPM
  55.     +20    256     (byte) Pattern order table
  56.  
  57.             Patterns:
  58.             ---------
  59.  
  60.       ?      4    (dword) Pattern header length
  61.      +4      1     (byte) Packing type (always 0)
  62.      +5      2     (word) Number of rows in pattern (1..256)
  63.      +7      2     (word) Packed patterndata size
  64.             << Note! This is zero if the pattern is
  65.             completely empty and no pattern data
  66.             follows! >>
  67.  
  68.       ?      ?        Packed pattern data
  69.  
  70.             Instruments:
  71.             ------------
  72.  
  73.       ?      4    (dword) Instrument size << header that is >>
  74.      +4     22     (char) Instrument name
  75.     +26      1     (byte) Instrument type (always 0)
  76.             << This seems pretty random, don't
  77.             assume it's zero >>
  78.     +27      2     (word) Number of samples in instrument
  79.  
  80.    If the number of samples > 0, then the this will follow:
  81.  
  82.    !     +29      4  (dword) Sample header size
  83.    !     +33     96   (byte) Sample number for all notes
  84.    !    +129     48   (byte) Points for volume envelope
  85.    !    +177     48   (byte) Points for panning envelope
  86.    !    +225      1   (byte) Number of volume points
  87.    !    +226      1   (byte) Number of panning points
  88.    !    +227      1   (byte) Volume sustain point
  89.    !    +228      1   (byte) Volume loop start point
  90.    !    +229      1   (byte) Volume loop end point
  91.    !    +230      1   (byte) Panning sustain point
  92.    !    +231      1   (byte) Panning loop start point
  93.    !    +232      1   (byte) Panning loop end point
  94.    !    +233      1   (byte) Volume type: bit 0: On; 1: Sustain; 2: Loop
  95.    !    +234      1   (byte) Panning type: bit 0: On; 1: Sustain; 2: Loop
  96.    !    +235      1   (byte) Vibrato type
  97.    !    +236      1   (byte) Vibrato sweep
  98.    !    +237      1   (byte) Vibrato depth
  99.    !    +238      1   (byte) Vibrato rate
  100.    !    +239      2   (word) Volume fadeout
  101.    !    +241      2   (word) Reserved
  102.     << "Instrument Size" field tends to be more than the
  103.     actual size of the structure documented here (it
  104.     includes also the extended instrument sample header
  105.     above). So remember to check it and skip the additional
  106.     bytes before the first sample header >>
  107.    !
  108.    !                 Sample headers:
  109.    !                 ---------------
  110.    !
  111.    !       ?      4  (dword) Sample length
  112.    !      +4      4  (dword) Sample loop start
  113.    !      +8      4  (dword) Sample loop length
  114.    !     +12      1   (byte) Volume
  115.    !     +13      1   (byte) Finetune (signed byte -16..+15)
  116.    !     +14      1   (byte) Type: Bit 0-1: 0 = No loop, 1 = Forward loop,
  117.    !                        2 = Ping-pong loop;
  118.    !                     4: 16-bit sampledata
  119.    !     +15      1   (byte) Panning (0-255)
  120.    !     +16      1   (byte) Relative note number (signed byte)
  121.    !     +17      1   (byte) Reserved
  122.    !     +18     22   (char) Sample name
  123.  
  124.     << Note! After the instrument header the file contains
  125.     ALL sample headers for the instrument followed by the
  126.         sample data for all samples.
  127.  
  128.         Also note that it is possible that samples have loops with
  129.         length zero. In that case the loops just have to be skipped. >>
  130.  
  131.    !
  132.    !                 Sample data:
  133.    !                 ------------
  134.    !
  135.    !       ?      ?         Sample data (signed): The samples are stored
  136.    !                 as delta values. To convert to real data:
  137.    !
  138.    !                 old=0;
  139.    !                 for i=1 to len
  140.    !                new=sample[i]+old;
  141.    !                sample[i]=new;
  142.    !                old=new;
  143.  
  144.  
  145.  
  146.    ***********************
  147.    *   Pattern format:     *
  148.    ***********************
  149.  
  150.    The patterns are stored as ordinary MOD patterns, except that each
  151.    note is stored as 5 bytes:
  152.  
  153.       ?      1     (byte) Note (0-71, 0 = C-0)
  154.             << Hah. Actually note numbers are 1-96,
  155.             97 being the key-off note (try to find
  156.             that in the documentation! >>
  157.      +1      1     (byte) Instrument (0-128)
  158.             << More like 1-128 >>
  159.      +2      1     (byte) Volume column byte (see below)
  160.      +3      1     (byte) Effect type
  161.      +4      1     (byte) Effect parameter
  162.  
  163.    A simle packing scheme is also adopted, so that the patterns not become
  164.    TOO large: Since the MSB in the note value is never used, if is used for
  165.    the compression. If the bit is set, then the other bits are interpreted
  166.    as follows:
  167.  
  168.       bit 0 set: Note follows
  169.       1 set: Instrument follows
  170.       2 set: Volume column byte follows
  171.       3 set: Effect follows
  172.       4 set: Guess what!
  173.  
  174.    It is very simple, but far from optimal. If you want a better,
  175.    you can always repack the patterns in your loader.
  176.  
  177.  
  178.  
  179.    ******************************
  180.    *   Volumes and envelopes:    *
  181.    ******************************
  182.  
  183.    The volume formula:
  184.  
  185.    FinalVol=(FadeOutVol/65536)*(EnvelopeVol/64)*(GlobalVol/64)*(Vol/64)*Scale;
  186.  
  187.    << The FadeOutVol is originally 65536 and is decremented by
  188.    instrument.fadeout each tick after note is released >>
  189.  
  190.    The panning formula:
  191.  
  192.    FinalPan=Pan+(EnvelopePan-32)*(128-Abs(Pan-128))/32;
  193.  
  194.    << Note that the panning envelope values range from 0-64, not
  195.    -128 - +127 >>
  196.  
  197.       Envelope:
  198.       ---------
  199.  
  200.    The envelopes are processed once per frame, instead of every frame where
  201.    no new notes are read. This is also true for the instrument vibrato and
  202.    the fadeout. Since I am so lazy and the tracker is rather self-explaining
  203.    I am not going to write any more for the moment.
  204.  
  205.    << Anyone have ANY idea how instrument autovibrato works? >>
  206.  
  207.  
  208.    ********************************
  209.    *   Periods and frequencies:   *
  210.    ********************************
  211.  
  212.    PatternNote = 0..95 (0 = C-0, 95 = B-7)
  213.     << Blah: Note = 1..96, 1 = C-0, 97 = key off >>
  214.  
  215.    FineTune = -128..+127 (-128 = -1 halftone, +127 = +127/128 halftones)
  216.    RelativeTone = -96..95 (0 => C-4 = C-4)
  217.  
  218.    RealNote = PatternNote + RelativeTone; (0..118, 0 = C-0, 118 = A#9)
  219.     << Hah: 1..119, 1 = C-0, 119 = A#9 >>
  220.  
  221.       Linear frequence table:
  222.       -----------------------
  223.  
  224.    Period = 10*12*16*4 - Note*16*4 - FineTune/2;
  225.    Frequency = 8363*2^((6*12*16*4 - Period) / (12*16*4));
  226.  
  227.       Amiga frequence table:
  228.       ----------------------
  229.  
  230.    Period = (PeriodTab[(Note MOD 12)*8 + FineTune/16]*(1-Frac(FineTune/16)) +
  231.          PeriodTab[(Note MOD 12)*8 + FineTune/16]*(Frac(FineTune/16)))
  232.         *16/2^(Note DIV 12);
  233.       (The period is interpolated for finer finetune values)
  234.    Frequency = 8363*1712/Period;
  235.  
  236.    << The interpolation code above doesn't work because of
  237.    several reasons:
  238.     1. It does not interpolate (try adding 1 to the
  239.     PeriodTab index in the second line)
  240.     2. It may go past the table beginning for negative
  241.     finetune values
  242.    Write your own interpolation routine instead - it's not that
  243.    hard. >>
  244.  
  245.    PeriodTab = Array[0..12*8-1] of Word = (
  246.       907,900,894,887,881,875,868,862,856,850,844,838,832,826,820,814,
  247.       808,802,796,791,785,779,774,768,762,757,752,746,741,736,730,725,
  248.       720,715,709,704,699,694,689,684,678,675,670,665,660,655,651,646,
  249.       640,636,632,628,623,619,614,610,604,601,597,592,588,584,580,575,
  250.       570,567,563,559,555,551,547,543,538,535,532,528,524,520,516,513,
  251.       508,505,502,498,494,491,487,484,480,477,474,470,467,463,460,457);
  252.  
  253.    << Note! The period table is made for 1-based note numbers, so in
  254.       practise it contains the period values for B-3 to G#4. Fun. >>
  255.  
  256.  
  257.    *************************
  258.    *   Standard effects:   *
  259.    *************************
  260.  
  261.       0      Appregio        << ;) >>
  262.       1  (*) Porta up
  263.       2  (*) Porta down
  264.       3  (*) Tone porta
  265.       4  (*) Vibrato
  266.       5  (*) Tone porta+Volume slide
  267.       6  (*) Vibrato+Volume slide
  268.       7  (*) Tremolo
  269.       8      Set panning
  270.       9      Sample offset
  271.       A  (*) Volume slide
  272.       B      Position jump
  273.       C      Set volume
  274.       D      Pattern break
  275.       E1 (*) Fine porta up
  276.       E2 (*) Fine porta down
  277.       E3     Set gliss control
  278.       E4     Set vibrato control
  279.       E5     Set finetune
  280.       E6     Set loop begin/loop
  281.       E7     Set tremolo control
  282.       E9     Retrig note
  283.       EA (*) Fine volume slide up
  284.       EB (*) Fine volume slide down
  285.       EC     Note cut
  286.       ED     Note delay
  287.       EE     Pattern delay
  288.       F      Set tempo/BPM
  289.       G      Set global volume
  290.       H  (*) Global volume slide
  291.       K      Key off        << also note number 97 >>
  292.       L      Set envelope position
  293.       P  (*) Panning slide
  294.       R  (*) Multi retrig note
  295.       T      Tremor
  296.       X1 (*) Extra fine porta up
  297.       X2 (*) Extra fine porta down
  298.  
  299.       (*) = If the command byte is zero, the last nonzero byte for the
  300.         command should be used.
  301.  
  302. << The commands are reasonably Protracker compatible although
  303. not all PT "features" (some might call them replay routine bugs)
  304. are implemented. >>
  305.  
  306.    *********************************
  307.    *   Effects in volume column:   *
  308.    *********************************
  309.  
  310.    All effects in the volume column should work as the standard effects.
  311.    The volume column is interpreted before the standard effects, so
  312.    some standard effects may override volume column effects.
  313.  
  314.    Value      Meaning
  315.  
  316.       0       Do nothing
  317.     $10-$50   Set volume Value-$10
  318.       :      :      :
  319.       :      :      :
  320.     $60-$6f   Volume slide down
  321.     $70-$7f   Volume slide up
  322.     $80-$8f   Fine volume slide down
  323.     $90-$9f   Fine volume slide up
  324.     $a0-$af   Set vibrato speed
  325.     $b0-$bf   Vibrato
  326.     $c0-$cf   Set panning
  327.     $d0-$df   Panning slide left
  328.     $e0-$ef   Panning slide right
  329.     $f0-$ff   Tone porta
  330.  
  331.  
  332. << And here goes one more section that this document really
  333. should have had:
  334.  
  335.    ********************
  336.    *  General layout  *
  337.    ********************
  338.  
  339.    The layout of a typical XM is like this:
  340.  
  341.    XM header (up to and excluding header size field, now 60 bytes)
  342.     Rest of the header (length including header size field)
  343.    Pattern 0 header (length in header)
  344.     Pattern 0 data (length in header)
  345.    Pattern 1 header (length in header)
  346.     Pattern 1 data (length in header)
  347.    ... (* number of patterns)
  348.    Instrument 0 header (length in size field is this and next one together)
  349.     if (numSample > 0)
  350.         Extra header
  351.             Sample 0 header (size in instrument extra header)
  352.             Sample 1 header (size in instrument extra header)
  353.             ... (* number of samples in instrument)
  354.                 Sample 0 data (length in sample header)
  355.                 Sample 1 data (length in sample header)
  356.                 ... (* number of samples in instrument)
  357.    Instrument 1 header (length in size field is this and next one together)
  358.     ... (* number of instruments)
  359. >>
  360.  
  361.  
  362.  
  363.  ============================================================================
  364.  
  365.    This should be just about everything (I hope?). You will probably need
  366.    some information about the MOD format and maybe about S3M.
  367.  
  368.    Have fun!
  369.    << And we sure had! >>
  370.  
  371.          Fredrik Huss / Mr.H of Triton
  372.  
  373.    << Jarno Paananen & Petteri Kangaslampi - Guru & Alfred / S2
  374.  
  375.    If you have questions that you think we might be able to
  376.    answer, have found out more mistakes in this document, or
  377.    know how instrument autovibrato works, e-mail us at:
  378.    Jarno: p153737@cc.tut.fi
  379.       _or_
  380.    Petteri: pekangas@sci.fi
  381.    >>
  382.